home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 2 / ETO Development Tools 2.iso / Tools - Objects / MacApp / MacApp CD Release / MacApp 2.0.1 (Many Libraries) / Interfaces / CIncludes / UMenuSetup.h < prev    next >
Encoding:
Text File  |  1990-10-25  |  13.1 KB  |  264 lines  |  [TEXT/MPS ]
  1. /*[a-,body+,h-,o=100,r+,rec+,t=4,u+,#+,j=20/57/1$,n-]*/
  2. /* UMenuSetup.p */
  3. /* Copyright © 1984-1990 Apple Computer Inc.  All rights reserved. */
  4.  
  5. /*
  6.             T H E O R Y   O F     O P E R A T I O N
  7.  
  8. This unit provides two features:  It implements a command numbering
  9. system that is independent of menu/item placement, and implements a
  10. framework for optimizing menu setups.
  11.  
  12. The command numbering system works by assigning commands a unique
  13. integer number, and providing a mechanism for mapping command numbers
  14. to menu/item pairs.  A set of routines are provide to manipulate
  15. commands via their command number rather than their menu and item
  16. numbers.
  17.  
  18. Each command can be assigned an integer command number from 1 to
  19. 32767.    To associate a command number with a menu item, menu resources
  20. are defined with the 'cmnu' resource type--not the 'MENU' type.  The
  21. 'cmnu' type is just like the 'MENU' type, with an additional command
  22. number field for each menu item.  The PostRez Tool converts the
  23. 'cmnu' output of Rez into equivalent 'MENU' resources and one 'mntb'
  24. resource.    The 'mntb' resource maps command numbers to menu/item pairs.
  25.  
  26. The items of some menus cannot be determined until run-time.  The font
  27. menu is an example.  In such cases, no command number is assigned by
  28. you.  Instead, the command number is equal to -(256 * menu + item).
  29.  
  30. The procedure CmdToMenuItem converts a command number to a menu id
  31. and item number by the following method:
  32.  
  33. - If the command number is positive, the command table is searched
  34. for the number. If it is found, CmdToMenuItem returns the corre-
  35. sponding menu id and item number.  Otherwise the menu and item are
  36. zero.
  37.  
  38. - If the command number is negative, the menu number is the upper eight
  39. bits, and the item number the lower eight bits, of the absolute value
  40. of the command number.    (This implies that menu id's must be <= 127
  41. and item numbers must be <= 255.)
  42.  
  43. The function CmdFromMenuItem converts menu/items to command numbers by
  44. the following method:
  45.  
  46. - If the item number is positive, the command table is search for the
  47. given menu/item pair.  If found, the corresponding command number is
  48. returned.  If not found, the number returned is equal to
  49. -(256 * menu + item).
  50.  
  51. - If the item number is negative, the number returned is equal to
  52. -item number.
  53.  
  54. Note that CmdToMenuItem and CmdFromMenuItem work regardless of whether
  55. the command is actually installed in the menu bar.    MacApp takes
  56. advantage of this feature by having a set of generic "buzz" commands,
  57. whose primary use is to set the name of the Undo command (e.g. 'Undo
  58. Drawing').
  59.  
  60. The second feature of this unit is to optimize menu setups (changing
  61. the appearance of menus and items).  Normally, each call to CheckItem,
  62. SetItemStyle and SetCmdIcon in turn calls CalcMenuSize because the width
  63. or height of the menu may have changed.  If menu setups are done all at
  64. one time, then CalcMenuSize can be deferred until the end of the setup
  65. process.  The procedure PerformMenuSetup implements this mechanism.  It
  66. relies on the fact that menu setups are done all at once, and that you
  67. will call SetCmdName, SetItemStyle and SetCmdIcon instead of SetItem,
  68. SetItemStyle and SetCmdIcon.  It works only for menus whose id is from
  69. 1 to mLastMenu.  Menus with IDs greater than mLastMenu are not affected
  70. by this scheme.
  71.  
  72. PerformMenuSetup accepts one parameter, a procedure which actually
  73. implements the menu appearance changes.  SetupMenus performs the
  74. following steps:
  75.  
  76. - Before calling your menu setup procedure, StartupMenuSetup is called.
  77. It disables all menus and items, remembers the current
  78. menu proc and enabled flags of each menu, and sets the MenuProc of
  79. each menu to gHNullMenuProc, thereby disabling CalcMenuSize.
  80. - Your procedure is called.  It in turn calls SetCmdName,
  81. SetCmdStyle, SetCmdIcon, Enable, EnableCheck, or a
  82. Toolbox routine (provided it isn't SetItem, SetItemStyle or
  83. SetCmdIcon).
  84. - Menus with at least one enabled item are enabled, CalcMenuSize is
  85. called for those menus that need it, each menu's menuproc is restored,
  86. and DrawMenuBar is called if the enabled state of any menu changed.
  87. */
  88.  
  89. #ifndef  __UMenuSetup__
  90. #define __UMenuSetup__  0
  91. #endif
  92. #if  ! __UMenuSetup__
  93. #define __UMenuSetup__  1
  94.  
  95.         /* • Required for this unit's interface. Auto-Include them */
  96. #ifndef  __TYPES__
  97. #include "Types.h"
  98. #endif
  99. #ifndef  __MENUS__
  100. #include "Menus.h"
  101. #endif
  102.  
  103. const unsigned long kMNTBbyCmdNumber    = 'mntb';        /* menu command number table type */
  104. const short kIDMNTBbyCmdNumber    = 128;                    /* menu command number table ID */
  105.  
  106. const short mFirstMenu            = 1;                    /* MacApp manages menu titles
  107.                                                          mFirstMenu..mLastMenu generically */
  108. const short mApple                = mFirstMenu;            /* MacApp does not disable any commands in
  109.                                                          this menu */
  110. const short mFile                = mApple + 1;            /* Default ID of the File menu */
  111. const short mEdit                = mFile + 1;            /* Default ID of the Edit menu */
  112.  
  113. const short mDebug                = 900;                    /* read in if debugging is turned on; number
  114.                                                          corresponds with debugging command numbers
  115.                                                          */
  116. const short mLastMenu            = 63;                    /* MacApp disables menu titles
  117.                                                          mFile..mLastMenu generically */
  118.  
  119. typedef short CmdNumber;                                /* CmdNumbers tell MacApp what verb is
  120.                                                          intended after mapping from menu/item. */
  121.  
  122. extern pascal Boolean gMenusAreSetup;                    /* set FALSE before every event; set TRUE by
  123.                                                          SetupTheMenus, which is called at Idle
  124.                                                          Begin; if your DoIdle changes the target
  125.                                                          or makes other changes that would alter
  126.                                                          the appearance of menus, you must set
  127.                                                          gMenusAreSetup to FALSE there. */
  128. extern pascal Boolean gRedrawMenuBar;                    /* if TRUE, then DrawMenuBar will be called
  129.                                                          by TApplication.SetupTheMenus. If you have
  130.                                                          menus that are not handled by MacApp, your
  131.                                                          implementation(s) of DoSetupMenus can set
  132.                                                          this to TRUE to force the menu bar to be
  133.                                                          redrawn. */
  134. #if  qDebug
  135. extern pascal Boolean gTraceSetupMenus;
  136. #endif
  137.  
  138.         /* The following routines all recognize command numbers of the form -(256 * menu + item) and
  139.         -(256 * menu). The former is used when there is no command number; the latter to
  140.         enable/disable a whole menu (rare) */
  141.  
  142. extern pascal Boolean CmdEnabled(CmdNumber cmd);
  143.         /* Returns true if the given cmd is currently enabled. */
  144.  
  145. extern pascal CmdNumber CmdFromMenuItem(short menu, short item);
  146.         /* Returns the command number for the given menu ID and item number. If the item number is
  147.         positive, the command table is search for the given menu/item pair. If found, the
  148.         corresponding command number is returned. If not found, the number returned is equal to
  149.         -(256 * menu + item). If the item number is negative, the number returned is equal to -item
  150.         number. */
  151.  
  152. extern pascal void CmdToMenuItem(CmdNumber aCmd, short *menu, short *item);
  153.         /* CmdToMenuItem returns the menu ID and item number of the given command. If aCmd is
  154.         positive, the command table is searched for aCmd. If it is found, CmdToMenuItem returns the
  155.         corresponding menu ID and item number. Otherwise menu and item are set to zero. If aCmd is
  156.         negative, the menu number is the upper eight bits, and the item number the lower eight
  157.         bits, of the absolute value of aCmd. (This implies that menu id's must be <= 127 and item
  158.         numbers must be <= 255.) */
  159.  
  160. extern pascal MenuHandle CmdToComponents(CmdNumber cmd, short *menuNo, short *itemNo);
  161.         /* CmdToComponents returns the menu ID and item number of the given command. as well as
  162.         the MenuHandle if the cmd exists.  Otherwise it returns nil. */
  163.  
  164. extern pascal void CmdToName(CmdNumber aCmd, StringPtr menuText);
  165.         /* Return the text of the menu item for the given command. */
  166.  
  167. extern pascal void EachMenuDo(pascal void (*DoToMenu)(MenuHandle aMenuHandle, Boolean isHierarchical
  168.    , void *DoToMenu_StaticLink), void *DoToMenu_StaticLink, Boolean includeHierarchical);
  169.         /* Sequences thru each menu in menu bar with ID in [0..mLastMenu], calling DoToMenu for each
  170.         menu. Handles mDebug as a special case. */
  171.  
  172. extern pascal void Enable(CmdNumber aCmd, Boolean canDo);
  173.         /* Enable or disable a command */
  174.  
  175. extern pascal void EnableCheck(CmdNumber aCmd, Boolean canDo, Boolean checkIt);
  176.         /* Enable/Disable and check/uncheck a command */
  177.  
  178. extern pascal MenuHandle GetResMenu(short menuResID);
  179.         /* Utility that just does GetResource('MENU', resourceID), so that it works for menus not
  180.         currently in the menu bar. (You cannot call GetMenu more than once for the same menu, so
  181.         you can use this (or MAGetMenu which is preferred) instead.) */
  182.  
  183. extern pascal void InitUMenuSetup(void);
  184.         /* Initializes this unit, and must be called before using any other part of this unit. Loads
  185.         the command table and sets up the null menu proc. */
  186.  
  187. extern pascal Handle MAGetNewMBar(short menuRsrcID);
  188.         /* Equivalent to the Menu Manager's GetNewMBar except it explicitly sets the menu bar's
  189.         colors.*/
  190.  
  191. extern pascal void MAInsertMenu(MenuHandle theMenu, short beforeID);
  192.         /* Equivalent to the Menu Manager's InsertMenu with the addition that the MAInsertMenu looks
  193.         for an 'mctb' resource whose id is the menu's id, and if it is present applies the 'mctb'
  194.         to the menu.*/
  195.  
  196. extern pascal MenuHandle MAGetMenu(short menuNo);
  197.         /* Not quite equivalent to GetMenu because it doesn't load the menuDefProc or color tabl
  198.            e yet.
  199.         It does, however, let you get the menuhandle without calling GetMenu more than o
  200.    nce.  It tries
  201.         the menubar first and then calls GetResMenu if necessary. */
  202.  
  203. extern pascal void NeedCalcMenuSize(MenuHandle aMenuHandle);
  204.         /* This procedure is called as part of the menu setup process and indicates that the given
  205.         menu needs CalcMenuSize. You must explicitly call this if you use change a menu by means
  206.         other than those supplied in this unit (e.g. you insert or delete items from a menu).
  207.         Failure to do so will result in improperly sized menus. */
  208.  
  209. extern pascal void SetCmdIcon(CmdNumber aCmd, short menuIcon);
  210.         /* You should call this (instead of the Toolbox's SetCmdIcon) for menus that are in the 
  211.            range
  212.         [1..mLastMenu]. In addition to changing the menu this tells MacApp that the menu's size
  213.         needs to be recomputed. */
  214.  
  215. extern pascal void SetCmdName(CmdNumber aCmd, StringPtr menuText);
  216.         /* You should call this (instead of the Toolbox's SetItem) for menus that are in the range
  217.         [1..mLastMenu]. In addition to changing the menu this tells MacApp that the menu's size
  218.         needs to be recomputed. */
  219.  
  220. extern pascal void SetIndCmdName(CmdNumber aCmd, short rsrcID, short strIndex);
  221.         /* Does a GetIndString with the rsrcID & strIndex; and then a SetCmdName. */
  222.  
  223. extern pascal void SetMenuState(CmdNumber aCmd, short rsrcID, short falseBuzzItem, short 
  224.    trueBuzzItem, Boolean stateVariable);
  225.         /* IF stateVariable THEN
  226.             SetIndCmdName(aCmd, rsrcID, trueBuzzItem)
  227.         ELSE
  228.             SetIndCmdName(aCmd, rsrcID, falseBuzzItem);
  229.         */
  230.  
  231. extern pascal void SetStyle(CmdNumber aCmd, unsigned short aStyle);
  232.         /* You should call this (instead of the Toolbox's SetItemStyle) for menus that are in the
  233.         range [1..mLastMenu]. In addition to changing the menu this tells MacApp that the menu's
  234.         size needs to be recomputed. */
  235.  
  236. extern pascal void PerformMenuSetup(pascal void (*TheMenuSetterUpper)(void *
  237.    TheMenuSetterUpper_StaticLink), void *TheMenuSetterUpper_StaticLink);
  238.         /* Routine that perfoms the menu setup. */
  239.  
  240. extern pascal void InvalidateMenus(void);
  241.         /* Invalidate all the items on all the menus.  Just like invalidation for windows it doesn't
  242.         immediately change the visual appearance when you invalidate, it just means they are invalid
  243.         and should be "setup" before showing them to the user again.  */
  244.  
  245. extern pascal void ValidateMenus(void);
  246.         /* Validate all the items on all the menus.  Just like Validation for windows it doesn't
  247.         immediately change the visual appearance when you Validate, it just means they don't need
  248.         to be changed before showing them to the user again.  */
  249.  
  250. extern pascal Boolean MenusHavePendingUpdate(void);
  251.         /* TRUE if the menus are invalid and should be "setup" before showing them to the user.  */
  252.  
  253. extern pascal void InvalidateMenuBar(void);
  254.         /* Invalidate the menu bar.  It should be redrawn again.  */
  255.  
  256. extern pascal void ValidateMenuBar(void);
  257.         /* Validate the menu bar.  It doesn't need redrawing, its just fine thank you.  */
  258.  
  259. extern pascal Boolean MenuBarHasPendingUpdate(void);
  260.         /* TRUE if the menu bar is invalid and should be redrawn.  */
  261.  
  262. #endif
  263.  
  264.